메인 콘텐츠로 이동하기
  1. Hugo & Congo 문서/

시작하기

7 분
이 섹션에서는 Congo 테마를 이미 설치했다고 가정합니다.

Congo 테마에 포함된 구성 파일에는 테마가 인식하는 모든 가능한 설정이 포함되어 있습니다. 기본적으로 많은 설정은 주석 처리되어 있지만 간단히 주석을 해제하여 특정 기능을 활성화하거나 변경할 수 있습니다.

기본 구성 #

여기서는 한국어 초보 사용자들을 위해, 제 설정 파일을 예시로 사용합니다.

콘텐츠를 만들기 전에 몇 가지 설정을 해야 합니다. config.toml 파일에서 baseURLlanguageCode 매개변수를 설정합니다. languageCode는 콘텐츠를 작성할 때 사용할 기본 언어로 설정해야 합니다.

# config/_default/config.toml

baseURL = "http://localhost:1313/"

enableEmoji = true
enableGitInfo = true
hasCJKLanguage = true

theme = "congo"
defaultContentLanguage = "ko"

enableRobotsTXT = true
summaryLength = 0

[pagination]
  pagerSize = 10

[outputs]
  home = ["HTML", "RSS", "JSON"]

다음 단계는 언어 설정을 구성하는 것입니다. 물론 Congo는 다국어 설정을 지원하지만, 현재는 주요 언어만 구성하세요.

config 폴더에서 languages.en.toml 파일을 복사해서 languages.ko.toml 로 새로 저장합니다. 주요 언어가 영어인 경우에는 복사없이 파일을 그대로 사용할 수 있습니다.
그렇지 않으면 파일 이름에 올바른 언어 코드를 포함하도록 이름을 변경합니다. 예를 들어, 한국어의 경우 파일 이름을 languages.ko.toml로 변경합니다.

언어 설정 파일의 언어 코드는 config.toml 파일의 languageCode 설정과 일치해야 합니다.
# config/_default/languages.ko.toml

languageCode = "ko-KR"
languageName = "한국어"
languageDirection = "ltr"
weight = 1

title = "헤픈애의 해프닝"
copyright = "Handcrafted by Heppen © 2025"

[params]
  dateFormat = "2006/01/02"
  mainSections = ["posts", "hugo-docs", "hugo-samples"]
  description = "평범한 일상을 꿈꾸는 헤픈애의 헤픈 블로그"

[params.author]
  name = "헤픈애"
  image = "img/author.jpg"
  headline = "평범한 일상을 꿈꾸는 헤픈애"
  bio = "평범한 일상을 꿈꾸는 헤픈애"
  links = [
    # { x-twitter = "https://twitter.com/" },
    # { facebook = "https://facebook.com/" },
    # { linkedin = "https://linkedin.com/" },
    # { youtube = "https://youtube.com/" },
  ]

[params.author] 설정은 작성자 정보가 웹사이트에 표시되는 방식을 결정합니다. 이미지는 웹사이트의 assets/ 폴더에 배치해야 합니다. 링크는 나열된 순서대로 표시됩니다.

만약 더 자세한 정보가 필요하다면, Configuration 섹션에서 자세히 알아보세요.

색상 테마 #

Congo는 기본적으로 여러 색상 테마를 제공합니다. 테마를 변경하려면 colorScheme 테마 매개변수를 설정하세요. 유효한 옵션은 congo (기본값), avocado, cherry, fire, ocean, sapphireslate입니다.

색상 테마 설정 #

# config/_default/params.toml

colorScheme = "congo"

Congo는 테마 전체에서 사용되는 세 가지 색상 팔레트를 정의합니다. 각 기본 색상은 Tailwind에 포함된 색상을 기반으로 하는 열열 개의 그라데이션을 포함합니다.

Congo (default) #

Avocado #

Cherry #

Fire #

Ocean #

Sapphire #

Slate #

이들은 기본 테마이지만, 자신만의 테마를 만들 수도 있습니다. 자세한 내용은 Advanced Customisation 섹션을 참조하세요.

콘텐츠 정리 #

기본적으로 Congo는 특정 콘텐츠 유형을 사용하도록 강제하지 않습니다. 이렇게 하면 자유롭게 콘텐츠를 정의할 수 있습니다. 정적 사이트에는 pages, 블로그에는 posts, 포트폴리오에는 projects 를 사용할 수 있습니다.

디렉토리 구조 #

기본 Congo 프로젝트의 빠른 개요입니다. 모든 콘텐츠는 content 폴더 내에 배치됩니다.

.
├── assets
│   └── img
│       └── author.jpg
├── config
│   └── _default
├── content
│   ├── _index.md
│   ├── about.md
│   └── posts
│       ├── _index.md
│       ├── first-post.md
│       └── another-post
│           ├── aardvark.jpg
│           └── index.md
└── themes
    └── congo
여기서 주목해야 할 중요한 점은 content 디렉토리 내에서 일반 문서 페이지는 index.md로 명명되고 목록 페이지는 _index.md로 명명된다는 것입니다. 문서와 함께 제공되는 모든 자산은 인덱스 파일과 함께 있는 하위 디렉토리에 배치되어야 합니다.

테마는 Hugo 페이지 번들의 이점을 최대한 활용하기 위해 Hugo 콘텐츠 관리 기능을 사용합니다. 자세한 내용은 공식 Hugo 문서를 참조하세요.

피쳐, 커버 및 썸네일 이미지 #

Congo 테마는 문서 목록과 개별 문서 페이지 상단에 이미지를 표시할 수 있습니다. 지원되는 세 가지 이미지 유형이 있으며, 각각 자체 사용 사례가 있습니다. feature, coverthumb.

아래 예시에서는 first-post 문서에 대해 커버 및 썸네일 이미지가 사용되었습니다.

.
└── content
    └── posts
        ├── _index.md
        └── first-post
            ├── cover.jpg
            ├── index.md
            └── thumb.jpg

thumb 이미지는 문서 썸네일로 사용되며, 문서 목록에 표시됩니다. cover 이미지는 개별 문서 페이지의 문서 내용 상단에 표시됩니다.

A screenshot of an article with a thumbnail image
이 예시는 썸네일 이미지가 있는 문서를 보여줍니다.

최대 성능을 위해 썸네일 이미지는 자동으로 4:3 비율로 잘리고 조정됩니다. 커버 이미지는 자동으로 콘텐츠에 맞게 조정되지만, 모든 비율이 허용됩니다.

feature 이미지는 특별한 유형이며, 표시되면 문서 썸네일과 커버 이미지를 모두 대체합니다. 문서 메타데이터에도 표시되며, 콘텐츠가 Facebook 및 X와 같은 외부 네트워크에 공유될 때 포함됩니다.

테마는 문서 이미지를 자동으로 감지하고 사이트에 자동으로 추가합니다. Front Matter 데이터에 참조할 필요가 없으며, 페이지 리소스 내에 적절한 이름의 파일을 배치하기만 하면 됩니다. 이미지 파일 이름에 feature, cover 또는 thumb가 있으면 해당 용도로 사용됩니다.

Samples 섹션에는 이러한 이미지의 예시가 있습니다 (그리고 파일 구조를 보려면 소스 코드를 참조하세요).

태그 및 카테고리 #

Congo는 태그 및 카테고리를 사용하여 콘텐츠를 그룹화하는 것에 대해 유연합니다. 일부 사람들은 tagscategories 를 사용하여 콘텐츠를 그룹화하고 싶어하고, 다른 사람들은 topics 를 사용하고 싶어합니다.

Hugo는 기본적으로 포스트, 태그 및 카테고리를 사용합니다.
그러나 이것을 원하지 않는 경우에는 사용자 정의할 수 있습니다. 이를 위해 taxonomies.toml 구성 파일을 생성할 수 있습니다.

# config/_default/taxonomies.toml

tag = "tags"
topic = "topics"

이것은 기본 tagscategoriestagstopics 로 대체합니다. 태그 문법에 대한 자세한 내용은 Hugo Taxonomy docs 를 참조하세요.

새로운 태그를 생성하면 웹사이트의 탐색 링크를 올바른 섹션을 가리키도록 조정해야 합니다. 이는 아래에 설명되어 있습니다.

Congo는 두 가지 메뉴를 사용할 수 있습니다. 이는 콘텐츠와 레이아웃에 맞게 사용자 정의할 수 있습니다. main 메뉴는 웹사이트 헤더에 표시되고, footer 메뉴는 페이지 하단에 표시됩니다.

두 메뉴 모두 menus.en.toml 파일에 구성됩니다. 마찬가지로 언어 구성 파일과 같이, 사용하려는 언어가 다른 경우 파일 이름을 변경하고 en 을 사용하려는 언어 코드로 바꿉니다. 메뉴 링크는 가장 낮은 순서대로 정렬되고, 그 다음은 name 순서대로 정렬됩니다.

# config/_default/menus.ko.toml

[[main]]
  name = "Blog" # 메뉴에 표시될 이름
  pageRef = "posts" # content/posts 폴더와 연결
  weight = 10 # 메뉴 순서. 낮은 숫자가 먼저 표시됨

[[main]]
  name = "Topics"
  pageRef = "topics"
  weight = 30

[[main]]
  name = "Tags"
  pageRef = "tags"
  weight = 40

[[main]]
  identifier = "search"
  weight = 99
  [main.params]
    action = "search"

[[main]]
  identifier = "locale"
  weight = 100
  [main.params]
    action = "locale"

# 외부 웹사이트로 연결하는 링크
[[main]]
  name = "GitHub"
  url = "https://github.com/your-username"  # 외부 URL
  weight = 20
  [main.params]
    icon = "github"      # 아이콘 표시 (선택사항)
    showName = false     # 이름 숨기기 (선택사항)
    target = "_blank"    # 새 탭에서 열기 (선택사항)

name 매개변수는 메뉴 링크에 사용되는 텍스트를 지정합니다. 또한 선택적으로 title을 제공할 수 있으며, 이는 링크의 HTML 제목 속성을 채우는 데 사용됩니다.

pageRef 매개변수는 Hugo 콘텐츠 페이지와 태그를 쉽게 참조할 수 있도록 합니다. 이는 가장 빠른 방법이며, 쉽게 참조할 수 있습니다. 외부 URL을 링크하려면 url 매개변수를 사용할 수 있습니다.

추가 사용자 정의는 특별한 테마 매개변수를 사용하여 달성할 수 있습니다. 링크 내에 params 를 제공하면 icon, showName 을 사용하여 링크 텍스트를 전환할 수 있고, 선택적으로 URL에 대한 target 을 설정할 수 있습니다. 위의 예시에서, GitHub 링크는 아이콘만 표시되고 새 창에서 링크가 열립니다.

액션 링크는 특별한 기능을 수행하는 메뉴 항목입니다. Congo 테마에서 제공하는 3가지 주요 액션 링크가 있습니다.

유효한 테마 액션은 다음과 같습니다.

  • appearance 은 외관 전환기에 대한 링크를 생성합니다
  • locale 은 번역된 콘텐츠에 액세스하기 위한 드롭다운 선택기를 생성합니다
  • search 은 사이트 검색에 대한 링크를 생성합니다

모두 선택적이며, 필요하지 않은 경우 주석 처리할 수 있습니다. 기본 파일에 제공된 템플릿을 참조하세요.

# config/_default/menus.ko.toml

# 1. 다크모드/라이트모드 전환 버튼
[[main]]
  identifier = "appearance"
  weight = 80
  [main.params]
    action = "appearance"  # 테마 모드 전환
    icon = "sun"          # 아이콘 추가 (선택사항)

# 2. 언어 선택 드롭다운
[[main]]
  identifier = "locale"
  weight = 90
  [main.params]
    action = "locale"     # 언어 선택
    icon = "language"     # 아이콘 추가 (선택사항)

# 3. 검색 기능 버튼
[[main]]
  identifier = "search"
  weight = 100
  [main.params]
    action = "search"     # 검색 기능
    icon = "search"       # 아이콘 추가 (선택사항)

상세 구성 #

위의 단계는 최소한의 구성입니다. 이제 hugo server 를 실행하면 빈 Congo 웹사이트가 표시됩니다. 상세 구성은 설정 섹션에서 다룹니다.

개발/로컬 환경에서는 -D 플래그를 사용하여 빌드 및 실행하면 작성중인 글도 볼 수 있게됩니다. hugo server -D